New, in REALbasic 5.5, is the ability to create console applications using REALbasic.
* What is a console application?
A console application is one that contains no UI and works solely on the command line. In OS X, that means your application runs within the terminal, on Windows, it will run from the command prompt and on Linux, it will run from the command line or a terminal window.
Due to the lack of UI, the way a console application communicates with the user is through the Print and Input commands (or the StandardInputStream and StandardOutputStream classes). I will describe the new classes, global methods and API changes below.
* What program design principles are different with a console application?
When you make a GUI application, the program execution begins in the Application.Open event, and halts once you call Quit, or the user terminates your application thru the Quit menu. Your program will stay loaded in memory and running until some user interaction tells it to stop (or you call Quit in your code).
A console application behaves differently. The program execution begins in the ConsoleApplication.Run event and terminates once you exit the Run event (or call Quit). So basically, everything happens right inside of Run. If you would like your application to behave in a more GUI-like way (where it continues to run until the user interacts with it somehow), then you can still do that by placing a While loop in your Run event. For an example of how this works, please see the Event Driven Console.rb project template.
* What are the new classes that I can use for console applications?
There are three new classes, five new global methods, one new precompiler directive and one changed global method that pertain to the console application project type.
New Class: ConsoleApplication
This class has one event, which is the main entry point for the application.
Run( args() as String ) as Integer
'args' is an array of command line parameters that get passed in to the application. The first of the parameters will always be the application itself. The return value for the event will be passed along to the operating system as the return value for your entire application.
This class also has one method on it. It is used for making event-driven console applications.
DoEvents()
This does the same thing as Application.DoEvents, which is, yield time back to REALbasic so we can fire events, etc.
New Class: StandardInputStream
This class has two methods on it for dealing with input
Read( count as Integer ) as String
ReadLine() as String
Both Read and ReadLine will block until there is sufficient input to satisfy them. For Read, this means that your application's execution will halt until there are 'count' bytes available. It will then return those bytes as a string. For ReadLine, it will block until the user hits the enter key (or return, if you're using a Mac keyboard). Note that ReadLine will not return the newline character as a part of the string. Since there is only one StandardInputStream for the system, you do not need to create a StandardInputStream variable to use; you just use stdin.
New Class: StandardOutputStream
This class has two methods on it for dealing with output
Write( data as String )
WriteLine( data as String )
If you use WriteLine, a newline character will automatically be appended to the end of 'data'. If you do not wish to have a newline character, then use the Write method instead. Since there is only one StandardOutputStream for the system, you do not need to create a StandardOutputStream variable to use; you just use stdout (or stderr for the error stream).
New Global Methods:
Print( data as String )
This will print 'data' out to the terminal and append a newline character to the end of it. It is a shortcut for StandardOutputStream.WriteLine
Input() as String
This will retrieve a line from the terminal. It is a shortcut for the StandardInputStream.ReadLine. Note that it will not return the newline character as a part of the string.
stdin as StandardInputStream
Retreives the global handle to the standard input stream (typically the keyboard on the terminal, though it could be something like a file, serial control, socket, etc on some systems).
stdout as StandardOutputStream
Retreives the global handle to the standard output stream (typically the terminal window, tho it could be something else, just like the StandardInputStream).
stderr as StandardOutputStream
Retrieves the global handle to the standard error stream (typically the same as stdout, but it could be something different as well).
Changed Global Methods:
Quit( [status as Integer = 0] )
Quit now takes an optional parameter to return a status code. When you call Quit, it will automatically terminate your application (just like you were in a GUI project), and return the value that is passed in to it.
New Precompiler Directive:
TargetHasGUI
You can use this to write more general code in some of your classes. For example, you can now write a function like this:
